-> !SparkInfo.!Help 2.20 - 13-01-93 - Paul John Murphy
Copyright  1990,1991,1992,1993 Murphsoft - Paul John Murphy

Read this document carefully before using SparkInfo.

Program Description
===================

SparkInfo is an application which I have written to provide quick analysis
of an Archive. The program *should* cope with anything which Spark (up to
version 2.14) can create, and is based on information included with Spark on
the format of Archive files. The program *should* work on any Acorn
Archimedes.

Program Purpose
===============

To provide full information on files in an archive, even if it is corrupt or
truncated, and to aid recovery of files from a corrupt or truncated archive.

Program Distribution
====================

SparkInfo may be freely distributed, providing that the contents of the
archive remain the same, and no files are added to or modified in the
archive. The actual archiving method may be changed, as I have no desire to
force people to use Spark (even although it is excellent). I reserve all
other rights to SparkInfo, and it remains Copyright  1990,1991,1992,1993
Murphsoft - Paul John Murphy. This software costs nothing, but I still
retain all rights to it. This type of software is often called freeware, and
it is NOT the same as public domain (PD).

The distribution archive should contain the following files:
     Filename               Length   
     --------               ------
     !!ReadMe!!             77 bytes
     !SparkInfo.!Boot       282 bytes
     !SparkInfo.!Help       14389 bytes
     !SparkInfo.!Run        663 bytes
     !SparkInfo.!RunImage   28847 bytes
     !SparkInfo.!Sprites    2364 bytes
     !SparkInfo.!Sprites22  4496 bytes
     !SparkInfo.Messages    3590 bytes
     !SparkInfo.ORunImage   4049 bytes
     !SparkInfo.Sprites     4712 bytes
     !SparkInfo.Sprites22   9192 bytes
     !SparkInfo.Templates   5341 bytes

The original distribution archive was created using Spark 2.14 in Compress
16-bit mode.

ORunImage is the only non-essential file, and is v0.03 of SparkInfo which is
non-multitasking, in BASIC, and does not use the wimp. It may be of use to
some as an aid in recovering corrupt Sparkives.

If you are short of space, then the 22 variants of the Sprite files may
safely be removed from your working copy (or used to replace the ordinary
sprite files). However, the software must not be passed on without these
files, under any circumstances.

Program Guarantee
=================

Sorry, no guarantee (of any sort), if the program works, and saves your
life, great, I'm happy for you. If the program fails miserably, crashing
your machine, and trashing your hard disk, then hard luck, but not my
problem. The program works fine on my machines (A400/1 series, 4Mb RAM, 40Mb
ADFS hard disk, 46Mb SCSI hard disk, RISC OS 3.10; & A4, 4Mb RAM, 60Mb IDE
hard disk, RISC OS 3.10), and may work on others.
Unfortunately, I can no longer test under RISC OS 2, so correct operation is
even less guaranteed there!

Disclaimer
==========

I accept no responsibility for ANY problems with this software, or any
problems which this software may create.
Use is entirely at the risk of the user.

Instructions
============

SparkInfo is loaded by double-clicking on the application, and will do no
more than initialise and install itself on the icon-bar at this point. To
examine an archive, simply drag the file onto the SparkInfo icon (a spark on
top of a question mark), and a window will open with the first entry in the
archive being displayed.
Moving between files in the archive is done by clicking one of the
tape-recorder style icons at the top-left of the SparkInfo window. The
tape-recorder icons perform the following tasks (from left to right): start,
back, forward, end. Clicking SELECT on one of the icons performs that
action, and clicking ADJUST on one of the icons performs the opposite of
that action. There is also an option on the window menu to jump straight to
an individual file in the archive, if you know which it is relative to the
start (it is Goto=>File number).
You can also work with files in "offset mode". This is automatically entered
when you jump to a file by its offset (Goto=>Offset on the window menu).
Only the forward and start icons work in offset mode. Offsets are to the
archive marker character, from the start of the file.
You can save an individual file in a Sparkive by going to it (ie making it
the one being displayed), and using the save option on the window menu. It
will be saved as a Sparkive containing one entry (the file being examined
when save was selected).
SparkInfo may be terminated in the usual way (i.e. Quit on the Icon-Bar
Menu).
Once loaded, SparkInfo will try to grab any double-clicks on a file of type
&DDC, and act as if the file was dragged onto its icon. Also, if the RunType
environment variable is not set, then it will be set load SparkInfo when a
file type &DDC is executed.
When a Sparkive is opened (ie the SparkInfo window is open), the archive
headers may be altered. This can be done by turning off the "Safe" option
(using either the window icon, or the menu option), and simply changing the
values as required. Once the header has been updated as desired, it can be
written back to the Sparkive by choosing the "Write" option.
It is possible to do basic searches for files within Sparkives, based on
combinations of the information which can be displayed about a file within a
Sparkive. This is achieved using the Find menu option. The "Master Find
Spec" field is used to specify which of the other fields should be
considered in the search. If a field is included in the search, then it must
be EXACTLY matched for the a particular file to be found. "Go" will find the
first file after the current position in the Sparkive, using the movement
method selected (Headers/Search). "Count" will count the number of files
after the current position matching the search specification.

Comments
========

I wrote this program because I had a corrupted archive, and wished to
recreate as much of the contents as I could. The archive turned out to be
truncated, so I ended up making it the right length, with the correct
format, and this enabled Spark to accept it, so I could get all but the last
file (the one short of data) back. I leave it up to you to solve your own
problems, but hope that SparkInfo is helpful to you.
Information on the archive file format can be found in the !ReadMe for Spark
on the Spark disk from David Pilling (Spark's author and the only source of
Spark at the moment). SparkInfo is probably only of use to the more
technically minded, so please remember that if something is not broken, then
you cannot fix it, and should not attempt to do so.
I may in future improve SparkInfo to make it have an attempt at fixing
broken archives, as far as possible, but this and any other support is not
guaranteed.
Sub-directories of Archives (just an Archive within an Archive, effectively)
are not dealt with, just ignored. If you want info on a sub-directory, then
it must be extracted to a "normal" filing system, and then have SparkInfo
run on it (cannot easily be done with Spark, but is easy with Arc).
Alternatively, you can tell SparkInfo to go to the archive data offset for
the archive sub-directory in question, and this will allow examination of
the sub-directory, although some of the normal movement functions will not
be available.
SparkInfo in "Safe" mode only opens archives for input (i.e. OPENIN), so
should not corrupt or modify in any way any archive passed to it, unless
instructed to do so by the user.
Offsets are relative to the start of the file.
Only one archive may be open under SparkInfo at a time.
SparkInfo will only touch files of type DDC (Archive).
If any items displayed in the main SparkInfo window seem duplicated, or in a
strange order, then that is because they appear in that order in the archive
header.
SparkInfo knows nothing of the new ArcFS format which is probably a better
format from certain points of view.
SparkInfo also knows nothing of the Computer Concepts Compression format.
When I refer to a Sparkive, I basically mean an archive file which Spark is
capable of producing.
The editing facilities of SparkInfo should only be used on a copy of a
Sparkive, in case an error occurs, or a mistake is made.
Before using SparkInfo "in anger", I suggest that users experiment with it
on a copy of a good archive, on a spare disk. This enables you to get the
feel of using it, and discover the facilities available, without the risk of
(further) data loss.

Please feel free to make suggestions or comments about SparkInfo. These,
along with bug reports, are always welcome.

Known Bugs/Problems
===================

If the icon for a file type is not of the correct dimensions (i.e. 34x17
in mode 12 for file_xxx), then it may not be correctly displayed. This is
not really my problem as people should not be using sprites which are not
these sizes for file icons (according to Acorn guidelines).
Some errors currently cause the program to report the error and then
terminate, even although some may be pretty minor and the program could
possibly continue, as it is safer to just terminate.
Due to the file format for archives (not David Pilling's design, but
originating on PCs), stepping to the end of an archive, or stepping back a
file may be quite time consuming for larger archives. The delay is not too
bad however, only being a couple of seconds for a 3.5Mb archive on a hard
disk.
Under certain circumstances, a filing error may occur which causes all
subsequent filing operations to fail. This may cause abnormal operation or
results to occur. If this seems to be the case, dragging the archive onto
the SparkInfo icon or into the SparkInfo window should restore normal
operation.

Possible future enhancements
============================

More advanced search options (wildcards, more options, etc).
Better handling of subdirectories within archives.
Handling of ArcFS archive file format.
Repairing of Sparkives semi-automatically.

Acknowledgements
================

Arc is Beebug Arc by David Pilling.
Spark is by David Pilling, and is copyright  David Pilling.
Spark can be obtained by asking for Disc 16 : Spark and sending 5-99
(including P&P) to:
      David Pilling
      P.O. Box 22,
      Thornton Cleveleys,
      Blackpool.
      FY5 1LR.
      United Kingdom.
Acorn and Archimedes are trademarks of Acorn Computers Limited.
I am not connected with Spark, David Pilling, Acorn, or Beebug.

Version History
===============

0.00 19-01-91 - ArcInfo started.
0.01 21-01-91 - Added printing of file locations (absolute offsets) for
                archive headers and data.
0.02 03-02-91 - Modified into an application. Became SparkInfo. Still not
                multitasking.
0.03 08-02-91 - Fixed a bug where archive was left open if corrupt.
1.00 03-03-91 - Re-write. Now uses the desktop and multitasks.
1.01 21-04-91 - Fixed various bugs in date and time stamp decoding.
                Handle file icon slightly better, more as Filer and Spark do
                (small icon removed as well - it seemed unnecessary).
                Various other minor fixes and improvements.
2.00 12-01-92 - Re-write in Acorn Desktop C (Acorn ANSI C 4.00).
                Added support for interactive help (!Help).
                Changed certain routines, for better efficiency, made certain
                things slightly more sophistocated.
                Added save option to save an individual file as an archive to
                aid file recovery.
                Added option to jump to a specific file (by file number).
2.01 15-04-92 - Added "Messages" file support, making most messages external.
                Improved end of file handling (premature end of file caused
                problems).
                Fixed a few logic errors in moving to a given file in an
                archive (would sometimes give the file before or after the
                desired one, if not single-stepping forwards).
                Added "goto offset", so that any point of the file can be
                jumped to.
                Changed "archive header offset" to the more useful "archive
                marker offset".
2.02 18-04-92 - Fixed !Run file, so that Clib 3.75 was demanded for
                operation, since SparkInfo 2 was found not to work with Clib
                3.50 and 3.66, despite the ANSI C 4 documentation not really
                saying that older Clibs do not work.
                Never actually released.
2.10 06-07-92 - Re-designed main window, splitting icons where a translated
                form of the value is given into one icon for the value and
                one icon for the translation of the value.
                Also added various action icons so that most menu options are
                also available from the main window, and menu options for
                moving between files in the archive.
                Added search mode.
                Added editing facilities (*USE WITH CARE*).
                Added more trapping and checking for filing errors.
2.20 13-01-93 - Redesigned some of the SparkInfo sprites.
                Added code to ensure that header mode is the default when a
                Sparkive is initially opened.
                Added code to ensure that safe mode is the default when a
                Sparkive is initially opened.
                Tidied code.
                Redesigned windows slightly.
                Added basic "find file" options.
                Re-added code to make adjust close of main window open the
                directory which the Sparkive came from (it "fell out" in the
                BASIC -> C conversion!).
                Made RISC OS 3.1 aware, where possible (detailed information
                is not yet available, since the PRMs are not yet on general
                release).

Contacting Me
=============

I can be contacted in a number of ways:

InterNet: Paul.Murphy@ed.ac.uk
FidoNet: Paul Murphy @ 2:259/2.3@fidonet.org
Prestel: 038387270
Silicon Village: 038387270
Tessier Ashpool Online: Murph
Telecom Gold (Dialcom): 10074:MIK2056
Telex: 9312110135=PJ G
The World Of Cryton (2:252/102.0@fidonet.org): Paul Murphy
Alba Maximus (formerly Scottish Opus) (2:259/2.0@fidonet.org): Paul Murphy
